home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 426-450 / disk_432 / fifodev / fifo.doc < prev    next >
Text File  |  1992-05-06  |  7KB  |  183 lines
  1.  
  2.                 FIFO.DOC
  3.  
  4.          (c) Copyright 1990, Matthew Dillon, All Rights Reserved
  5.  
  6.             BIX:    mdillon
  7.             UUCP:    dillon@overload.Berkeley.CA.US
  8.  
  9.                   FIFO:
  10.  
  11.     FIFO: is like PIPE: but is based on fifo.library rather than its
  12.     own implementation.  Full master/slave support exists.  Since
  13.     FIFO: uses fifo.library, programs that require non-blocking IO
  14.     capability can access one side of a FIFO: connection via the
  15.     fifo.library instead of FIFO:
  16.  
  17.     The implementation of FIFO: and fifo.library is a billion times
  18.     better than that for PIPE:
  19.  
  20.     FIFO:<name>/<flags>
  21.  
  22.     <name>:    a valid fifo name
  23.  
  24.     name may be any combination of alpha numerics up to 64 chars long,
  25.     and is case sensitive.    FIFO: will append either "_m" or "_s" to
  26.     the name it supplies to fifo.library depending on whether master
  27.     mode or slave mode is selected.
  28.  
  29.     <flags>:    a valid combination of flags
  30.  
  31.     note that the combination "rw" is perfectly valid and provides
  32.     a full duplex connection pair between a master and a slave.
  33.  
  34.     r   open for read
  35.  
  36.     w   open for write
  37.  
  38.     c   open in cooked mode - FIFO: handles cooked data processing
  39.         of any writes done by the master side.  Additionally, FIFO:
  40.         echos data written to a master back to the master.
  41.  
  42.     e   EOF mode (when combined with 'w').  When this file handle
  43.         is closed, an EOF will be sent to the other side.
  44.  
  45.     k   KEEP mode.    If a writer opens a fifo, writes data, then
  46.         closes the fifo before a reader has a chance to open the
  47.         fifo, this flag prevents the data from being lost.
  48.  
  49.     m   select master (else slave).  See below
  50.  
  51.     t   tee read (this fifo gets an independant read stream for
  52.         monitoring purposes and does NOT interfere with other readers)
  53.  
  54.         Otherwise this fifo will compete with other fifos for read
  55.         data.
  56.  
  57.     s   SHELL mode, creates a separate message port for the handle
  58.         allowing the shell & progams to find their STDERR handle.
  59.         (i.e. the open-* packet works properly)
  60.  
  61.         WARNING: use of this option increases overhead in the FIFO:
  62.         device, use only for remote-shell applications.
  63.  
  64.     C   Send ^C to all (slaves or masters)
  65.     D   Send ^D to all (slaves or masters)
  66.     E   Send ^E to all (slaves or masters)
  67.     F   Send ^F to all (slaves or masters)
  68.  
  69.         NOTE:   something like "FIFO:fubar/C" is valid even though the
  70.         Open() will fail because no 'r' or 'w' options were specified.
  71.         The ^C (in this example) would be sent properly to all slaves.
  72.  
  73.         SEE REMCLI.C FOR EXAMPLE IMPLEMENTATION
  74.  
  75.  
  76.                    LINKED FIFOS
  77.  
  78.     FIFO: provides a full duplex connection using TWO fifo.library FIFOS.
  79.     Openning a fifo in master mode verses slave mode determines which
  80.     names are used for reading and writing.  You should note that when
  81.     a FIFO: handle is openned for both read and write, reading from the
  82.     handle actually accesses a different physical fifo than writing to
  83.     the handle.
  84.  
  85.          FIFO: device             fifo.library
  86.  
  87.     Open("FIFO:junk/w", 1005);              junk_s
  88.     Open("FIFO:junk/r", 1005);              junk_m
  89.     Open("FIFO:junk/rw",1005);              junk_s (w), junk_m (r)
  90.  
  91.     Open("FIFO:junk/wm", 1005);             junk_m
  92.     Open("FIFO:junk/rm", 1005);             junk_s
  93.     Open("FIFO:junk/rwm", 1005);            junk_m (w), junk_s (r)
  94.  
  95.                    REMOTE SHELL
  96.  
  97.     It is extremely easy to set up a fifo to interface a program with a
  98.     remote shell.  The FIFO: fully supports remote shells including
  99.     the ability to propogate ^C through ^F and handle stderr.
  100.  
  101.     Not only that, but programs which need to be able to access the
  102.     master side of a shell in a non-blocking fashion may access the
  103.     master side directly through FIFO.LIBRARY calls.  See FIFOLIB.DOC
  104.     for the function call list, see REMCLI.C for a working example.
  105.  
  106.     1> NewShell FIFO:name/rwkecs
  107.     1> run remcli name
  108.  
  109.     NOTES FOR SLAVE SIDE:
  110.     r   shell must be able to read the handle
  111.  
  112.     w   shell must be able to write the handle
  113.  
  114.     k   if slave side is started up first, any writes it does will
  115.         NOT be lost.
  116.  
  117.     e   when slave side closes the handle, an EOF will be sent to
  118.         the master side.
  119.  
  120.     c   run slave side in COOKED mode.  FIFO: will do command line
  121.         editing on any data sent to the slave side.  You do not specify
  122.         COOKED mode for the master side.  I repeat, do NOT specify
  123.         cooked mode for the master side.
  124.  
  125.     s   SHELL support, required on the slave specification when run
  126.         from NewShell, causes the handle to get its own message port.
  127.         (required to support Open("*", ...);
  128.  
  129.     NOTE:  YOU CAN RUN 'remcli name' MULTIPLE TIMES SIMULTANIOUSLY
  130.     USING THE SAME FIFO NAME.  All remcli's talking to the same
  131.     shell will get all output from the shell and additionally be
  132.     able to issue commands.  This can be extremely useful as a
  133.     monitoring tool.
  134.  
  135.         1> run remcli name
  136.         1> run remcli name
  137.  
  138.     You can also capture all shell interaction with this:
  139.  
  140.         1> cat FIFO:name/rt
  141.  
  142.     The 't' (TEE) specification is required to ensure you
  143.     do not screw up any other readers.  There is no limit on the
  144.     number of 'readers' monitoring a named fifo.
  145.  
  146.     If RemCLI tries to talk to a fifo that does not exist,
  147.     it will 'freeze' until the slave side does exist.  Meaning you
  148.     can run RemCLI before you start up the shell.
  149.  
  150.     CLOSING THE REMCLI WINDOW DOES NOT END THE SHELL.  You must type
  151.     'endcli' or 'endshell' to cause it to exit.  On the otherhand,
  152.     closing the remcli window and then reopenning will yield the
  153.     previous shell (which never exited).
  154.  
  155.                 PIPEING
  156.  
  157.     You can use the FIFO: device to pipe output from one program to the
  158.     input of another.  Note that you want to be sure to use the 'k' flag
  159.     in case the program generating the output generates only a little (and
  160.     is able to exit before you have a chance to start the reader).  You
  161.     also want to use the 'e' (EOF) option or the reader will not receive
  162.     an EOF, and you must make one side a master.
  163.  
  164.     1> cat >FIFO:xx/wkme
  165.     1> cat <FIFO:xx/r
  166.  
  167.     If you do not specify the 'e' EOF option then you can run multiple
  168.     program's output through the pipe sequentially, specifying the eof
  169.     option only for the last one.
  170.  
  171.     WARNING:    If you ^C the reader before it gets the EOF and exits
  172.     on its own, and the 'k' option is used, the named fifo will still
  173.     exist with the left over data in it.  This can be fixed by either
  174.     draining the data or by running the reader first, and writer second
  175.     and NOT using the 'k' option:
  176.  
  177.     1> cat <FIFO:xx/r
  178.     2> cat >FIFO:xx/wme
  179.  
  180.     In the above case the reader can be safely ^C'd without any left over
  181.     junk in the fifo (assuming the writer exits).
  182.  
  183.